home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / dos / pascal / shazam.exe / AINTRO.DOC < prev    next >
Text File  |  1992-09-01  |  15KB  |  405 lines
  1.                              ************
  2.                              INTRODUCTION
  3.                              ************
  4.  
  5. SHAZAM lets you define the entire interface of a Turbo Vision
  6. application in a simple ASCII file.
  7.  
  8. With a few keywords and a easy syntax, you can define and test
  9. anything from a simple test program to the TP 6.0 IDE, including
  10. online help, hints and context-sensitive StatusLines.
  11.  
  12. You only need the [ SUBMENU ] and [ STATUS ] keywords to develop an
  13. interface.  Other keywords and switches give you control over every
  14. aspect of how a program is generated.
  15.  
  16. You can develop and maintain Turbo Vision software using SHAZAM, too,
  17. not just generate interfaces.  Use the Dialog Editor to paint
  18. screens and the [ DIALOG ] keyword to include them; the [ UNIT ]
  19. keyword for automatic overlays and registration.
  20.  
  21. By flipping switches, you can change your program from pure code (for
  22. fast development) to a fully resourced, overlaid program with
  23. swap-to-disk capability for EXEC calls.
  24.  
  25. Keywords and switches are covered later.  First, let's take a look at
  26. the process of creating a program.  This will help you understand
  27. what the keywords and switches are, and why they exist.
  28.  
  29.  
  30.  
  31.                            ***************
  32.                            THE BIG PICTURE
  33.                            ***************
  34.  
  35.    Application Elements                    Program Elements
  36.  
  37.                        *.HLP                    *.EXE
  38.   *.DLG         *.DEF  *.TXT        *.REZ       *.OVR    *.$$$
  39.  ┌───────┐     ┌──────┬──────┐     ┌───────────┬────────┬────────┐
  40.  │       │     │Menus │Online│     │           │Program │Unitize │
  41.  │Dialogs│     │Status│ Help │     │ Resources │   &    │   &    │
  42.  │       │     │Hints │      │     │           │Overlays│ExecSwap│
  43.  └───┬───┘     └──┬───┴─┬──┬─┘     └─────┬─────┴───┬────┴───┬────┘
  44.      │            ├─────┘  │             └─────────┼────────┘
  45.      │            │        │                       │
  46.  ╔═══╧══╗      ╔══╧═══╗ ╔══╧═════╗            ╔════╧════╗
  47.  ║Dialog║      ║ Text ║ ║  Help  ║            ║   Code  ║
  48.  ║Editor║      ║Editor║ ║Compiler║            ║Generator║
  49.  ╚═══╤══╝      ╚═══╤══╝ ╚════╤═══╝            ╚════╤════╝
  50.      └─────────────┴────┬────┴─────────────────────┘
  51.                         │
  52.                    ▐▀▀▀▀▀▀▀▀▌
  53.                    ▐ SHAZAM ▌
  54.                    ▐▄▄▄▄▄▄▄▄▌
  55.  
  56.  
  57. This little diagram might make you wonder:  Can SHAZAM create your
  58. application as a fully resourced program with overlays, using
  59. multiple and/or foreign language sets of MenuBars, Context-sensitive
  60. StatusLines, Hints and Dialogs, compile Help Text, ensure updated
  61. resource values and by-the-way encapsulate everything so we can
  62. swap-to-disk for EXEC calls with minimum memory overhead?
  63.  
  64. Yes.
  65.  
  66. Load any example definition, then press "Ctrl-F9" to run it.
  67.  
  68.  
  69.  
  70.                           ******************
  71.                           EVOLVING A PROGRAM
  72.                           ******************
  73.  
  74. Let's look at the how you create a program by hand, then using SHAZAM.
  75.  
  76.  
  77. BY HAND
  78. =======
  79. First, we need an interface - something to start with.  Create a
  80. MenuBar, match up all those "NIL" and "Parentheses".  Now, for each
  81. interface item (cmXX), extend HandleEvent to call a dummy routine and
  82. create the routine (a window or MsgBox), so we can see something
  83. happen.  Next, figure out a help context for the drop-down menus, so
  84. we can at least have hints -- oops, gotta extend a new StatusLine
  85. object, so the hints show up.  Let's plug-in the "HelpFile" unit and
  86. dummy up some online Help, so the "F1" does something.  Look-up and
  87. re-use the help contexts we already defined -- oops, we don't need to
  88. define them anymore, the help compiler does it for us, so take'em
  89. out.  Don't forget to extend "GetPalette", to avoid the RED + WHITE +
  90. BLINK when help pops up.
  91.  
  92. Normally, you'd have to do all the above by hand, even for a three
  93. line program.  A partial list of the things you need to hand-code:
  94.  
  95.        MenuBar - Items & SubMenus
  96.     StatusLine - Items & Context ranges
  97.                  (PNewStatusLine w/Load & Store, for hints/resources)
  98.           cmXX - Command constant names & values
  99.         Params - MenuBar shortcuts
  100.          Hints - One-Liners for MenuBar & Dialog controls
  101.           kbXX - Which keyboard consta
  102.           hcXX - help context
  103.  
  104.  
  105. Using SHAZAM
  106. ============
  107. The following statements do ALL the above, in about 60 seconds:
  108.  
  109.     [ SUBMENU ] File        ;;file management
  110.     Open                    ;;open a new file
  111.     Save                    ;;save text in current window
  112.  
  113. Try a "copy & paste" of the three lines above into a file named
  114. SAMPLE.DEF, then press the Ctrl-F9 key to run the example.  You'll
  115. note that SHAZAM does a number of little "extras", such as adding
  116. context sensitive StatusLines where needed (these "extras" can be
  117. controlled via switches or the SETUP|Code dialog).
  118.  
  119. By now, you're probably got the idea that the distance from program
  120. "Conception to Construction" just got shorter!  As soon as you run
  121. through the ADEMO*.DEF series, putting meat on the bones of your
  122. applications is going to get a lot easier.  You should be able to get
  123. a new interface up & running almost as fast as you can think it up.
  124.  
  125.  
  126.  
  127.                              ************
  128.                              FLESH IT OUT
  129.                              ************
  130.  
  131. If you look at the source code for any generated definition, you'll
  132. see that command constants, help contexts and "dummy routines" are
  133. generated by SHAZAM for each Menu or Status item.  An entry is made
  134. in the generated HandleEvent, with each "cmXX" symbol matching a call
  135. to an "hdXX" routine of the same name.
  136.  
  137. Look at the *.HE file from any generated example.
  138.  
  139. Unless you say otherwise, the matching "hdXX" is a "dummy routine",
  140. created by SHAZAM, so generated programs will compile (and do
  141. something).
  142.  
  143. Of course, if you could make the Application^.HandleEvent call your
  144. own code, instead of dummy routines, SHAZAM could be used for actual
  145. programs, to develop and maintain software.
  146.  
  147. Somehow, you have to signal SHAZAM that an element of a Menu/Status
  148. item is either the real thing or must be dummied up.  That's where
  149. keywords and/or symbols come into play.
  150.  
  151.  
  152. MENU/STATUS ITEMS
  153. -----------------
  154. A quick glossary of terms:
  155.  
  156.     cmXX - A command constant/symbol
  157.     kbXX - A keyboard constant/symbol
  158.     hdXX - A HandlecommanD routine (actual or dummy)
  159.     hbXX - A HandleBroadcast routine
  160.     hcXX - A help context constant/symbol (MENU only)
  161.  
  162.  
  163. You can signal that an item is "real" by
  164.  
  165.     1.  Auto-scan of related *.EVT file
  166.     2.  Keywords - [ INTERNAL ] and [ EXTERNAL ]
  167.     3.  Symbols - "^^" (internal) and "%%" (external)
  168.  
  169.  
  170. AUTO-SCAN
  171. ---------
  172. If the matching *.EVT files exists, it is scanned for command and/or
  173. broadcast routines which have "hd" or "hb" prefixes.  If found, a
  174. matching "cmXX" is created, and entries will be made to the generated
  175. HandleEvent.
  176.  
  177. Each "hdXX" is added to HandleEvent, under the "evCommand" mask; look
  178. at a generated *.HE file and you will find a "HandlecommanD" section.
  179.  
  180. Each "hbXX" is added to HandleEvent, under the "evBroadcast" mask.
  181. Generate BCAST.DEF and look at "HandleBroadcast" in the BCAST.HE file.
  182.  
  183. This works dandy, since these are always at the Application level.
  184. But you may want to move code into units or include files, so we need
  185. another way to "reserve" names for cmXX, hdXX and hbXX symbols.
  186.  
  187.  
  188.  
  189. [ INTERNAL ] or [ EXTERNAL ]
  190. ----------------------------
  191. Remember, when a program is generated, each "XX" name generates a
  192. matched pair of "cmXX" and "hdXX" for HandleEvent.  And it's a given
  193. that any MenuBar, MenuBox or StatusLine item is going to be handled
  194. by either the Application or a TView descendant.
  195.  
  196. You need to decide:  Is the event handled by the Application or an
  197. object?  If by an object, like TFileEditor, it's [INTERNAL].  If by
  198. the Application, it's [EXTERNAL].
  199.  
  200. [ INTERNAL ] stuff we don't have to worry about, other than to tell
  201. SHAZAM that no cmXX or hdXX routines need to be cre